home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat3 / closedir.3 < prev    next >
Encoding:
Text File  |  1993-03-03  |  4.4 KB  |  133 lines
  1.  
  2.  
  3.  
  4. OPENDIR(3)          MINTLIB LIBRARY FUNCTIONS          OPENDIR(3)
  5.  
  6.  
  7. N✓NA✓AM✓ME✓E
  8.        directory,  opendir, readdir, telldir, seekdir, rewinddir,
  9.        closedir - directory operations
  10.  
  11. S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S
  12.        #include <dirent.h>
  13.  
  14.        DIR *opendir(const char *dirname);
  15.  
  16.        struct dirent *readdir(DIR *dirp);
  17.  
  18.        off_t telldir(DIR *dirp);
  19.  
  20.        void seekdir(DIR *dirp, off_t loc);
  21.  
  22.        void rewinddir(DIR *dirp);
  23.  
  24.        int closedir(DIR *dirp);
  25.  
  26. D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N
  27.        opendir opens the directory named by dirname  and  associ-
  28.        ates a directory stream with it. opendir returns a pointer
  29.        to be used to identify the directory stream in  subsequent
  30.        operations.  A  NULL pointer is returned if dirname cannot
  31.        be accessed or is not a directory, or if it cannot  malloc
  32.        enough memory to hold the whole thing.
  33.  
  34.        readdir  returns a pointer to the next directory entry. It
  35.        returns NULL upon reaching the end  of  the  directory  or
  36.        detecting and invalid seekdir operation.
  37.  
  38.        telldir  returns  the current location associated with the
  39.        named directory stream.
  40.  
  41.        seekdir sets the position of the next readdir operation on
  42.        the  directory stream. The new position reverts to the one
  43.        associated with the  directory  stream  when  the  telldir
  44.        operation  was  performed.  Values returned by telldir are
  45.        good only for the lifetime of the DIR pointer  from  which
  46.        they  are  derived.  If  the  directory is closed and then
  47.        reopened, the telldir value  may  be  invalidated  due  to
  48.        changes in the directory.
  49.  
  50.        rewinddir  resets  the  position  of  the  named directory
  51.        stream to the beginning of the directory. It  also  causes
  52.        the  directory stream to refer to the current state of the
  53.        corresponding directory, as a call to opendir  would  have
  54.        done.
  55.  
  56.        closedir  closes  the named directory stream and frees the
  57.        structure associated with the DIR pointer.
  58.  
  59. R✓RE✓ET✓TU✓UR✓RN✓N V✓VA✓AL✓LU✓UE✓ES✓S
  60.        opendir returns a pointer  of  type  DIR  on  success.  On
  61.  
  62.  
  63.  
  64. MiNT docs 0.1              3 March 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. OPENDIR(3)          MINTLIB LIBRARY FUNCTIONS          OPENDIR(3)
  71.  
  72.  
  73.        failure,  it  returns  NULL and sets errno to indicate the
  74.        error.
  75.  
  76.        readdir returns a pointer of object type struct dirent  on
  77.        success.  On  failure,  it  returns NULL and sets errno to
  78.        indicate the error. When  the  end  of  the  directory  is
  79.        encountered,   readdir   returns  NULL  and  leaves  errno
  80.        unchanged. The dirent structure is defined  in  <dirent.h>
  81.        and contains the following fields of interest:
  82.          struct dirent
  83.          {
  84.            long    d_ino;      /* garbage under TOS emulation  */
  85.            off_t   d_off;      /* position in directory        */
  86.            short   d_reclen;   /* length of d_name             */
  87.            ...                 /* various TOS-emulation fields */
  88.            char    *d_name;    /* name of the current file     */
  89.          };
  90.  
  91.        closedir returns 0 on succes, EIHNDL on failure.
  92.  
  93.        telldir returns the current location associated  with  the
  94.        specified directory stream.
  95.  
  96. E✓EX✓XA✓AM✓MP✓PL✓LE✓E
  97.        Sample code which searches a directory for entry `name' is:
  98.  
  99.            dirp = opendir(".");
  100.            for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
  101.              if (!strcmp(dp->d_name, name))
  102.              {
  103.                closedir(dirp);
  104.                return (FOUND);
  105.              }
  106.            closedir(dirp);
  107.            return (NOT_FOUND);
  108.  
  109. S✓SE✓EE✓E A✓AL✓LS✓SO✓O
  110.        D✓Do✓op✓pe✓en✓nd✓di✓ir✓r(✓(2✓2)✓),✓, D✓Dr✓re✓ea✓ad✓dd✓di✓ir✓r(✓(2✓2)✓),✓, D✓Dc✓cl✓lo✓os✓se✓ed✓di✓ir✓r(✓(2✓2)✓)
  111.  
  112. N✓NO✓OT✓TE✓ES✓S
  113.        As  memory  is  allocated  at every call to opendir, every
  114.        call to opendir should be matched by a corresponding  call
  115.        to closedir.
  116.  
  117.        When  MiNT is not active, readdir calls are emulated under
  118.        TOS. When that  happens,  various  fields  in  the  dirent
  119.        structure are used that are undefined when MiNT is active.
  120.        It is therefore advisable not to use those fields.
  121.  
  122.        Because of an error in the mintlibs and a change  in  MiNT
  123.        0.97,  programs  using  readdir from the mintlibs pl 24 or
  124.        below will die in MiNT 0.97 or higher.
  125.  
  126.  
  127.  
  128.  
  129.  
  130. MiNT docs 0.1              3 March 1993                         2
  131.  
  132.  
  133.